home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / CIncludes / Components.h < prev    next >
C/C++ Source or Header  |  1996-05-01  |  14KB  |  395 lines
  1. /*
  2.      File:        Components.h
  3.  
  4.      Contains:    Component Manager Interfaces.
  5.  
  6.      Version:    Technology:    System 7.5
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __COMPONENTS__
  19. #define __COMPONENTS__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24. #ifndef __MIXEDMODE__
  25. #include <MixedMode.h>
  26. #endif
  27.  
  28. #ifdef __cplusplus
  29. extern "C" {
  30. #endif
  31.  
  32. #if PRAGMA_IMPORT_SUPPORTED
  33. #pragma import on
  34. #endif
  35.  
  36. #if PRAGMA_ALIGN_SUPPORTED
  37. #pragma options align=mac68k
  38. #endif
  39.  
  40. #if FOR_SYSTEM7_AND_SYSTEM8_COOPERATIVE
  41.  
  42. enum {
  43.     kAppleManufacturer            = 'appl',                        /* Apple supplied components */
  44.     kComponentResourceType        = 'thng'                        /* a components resource type */
  45. };
  46.  
  47.  
  48. enum {
  49.     kAnyComponentType            = 0,
  50.     kAnyComponentSubType        = 0,
  51.     kAnyComponentManufacturer    = 0,
  52.     kAnyComponentFlagsMask        = 0
  53. };
  54.  
  55.  
  56. enum {
  57.     cmpWantsRegisterMessage        = 1L << 31
  58. };
  59.  
  60.  
  61. enum {
  62.     kComponentOpenSelect        = -1,                            /* ComponentInstance for this open */
  63.     kComponentCloseSelect        = -2,                            /* ComponentInstance for this close */
  64.     kComponentCanDoSelect        = -3,                            /* selector # being queried */
  65.     kComponentVersionSelect        = -4,                            /* no params */
  66.     kComponentRegisterSelect    = -5,                            /* no params */
  67.     kComponentTargetSelect        = -6,                            /* ComponentInstance for top of call chain */
  68.     kComponentUnregisterSelect    = -7,                            /* no params */
  69.     kComponentGetMPWorkFunctionSelect = -8                        /* some params */
  70. };
  71.  
  72. /* Component Resource Extension flags */
  73.  
  74. enum {
  75.     componentDoAutoVersion        = (1 << 0),
  76.     componentWantsUnregister    = (1 << 1),
  77.     componentAutoVersionIncludeFlags = (1 << 2),
  78.     componentHasMultiplePlatforms = (1 << 3)
  79. };
  80.  
  81. /* Set Default Component flags */
  82.  
  83. enum {
  84.     defaultComponentIdentical    = 0,
  85.     defaultComponentAnyFlags    = 1,
  86.     defaultComponentAnyManufacturer = 2,
  87.     defaultComponentAnySubType    = 4,
  88.     defaultComponentAnyFlagsAnyManufacturer = (defaultComponentAnyFlags + defaultComponentAnyManufacturer),
  89.     defaultComponentAnyFlagsAnyManufacturerAnySubType = (defaultComponentAnyFlags + defaultComponentAnyManufacturer + defaultComponentAnySubType)
  90. };
  91.  
  92. /* RegisterComponentResource flags */
  93.  
  94. enum {
  95.     registerComponentGlobal        = 1,
  96.     registerComponentNoDuplicates = 2,
  97.     registerComponentAfterExisting = 4
  98. };
  99.  
  100. struct ComponentDescription {
  101.     OSType                             componentType;                /* A unique 4-byte code indentifying the command set */
  102.     OSType                             componentSubType;            /* Particular flavor of this instance */
  103.     OSType                             componentManufacturer;        /* Vendor indentification */
  104.     unsigned long                     componentFlags;                /* 8 each for Component,Type,SubType,Manuf/revision */
  105.     unsigned long                     componentFlagsMask;            /* Mask for specifying which flags to consider in search, zero during registration */
  106. };
  107. typedef struct ComponentDescription ComponentDescription;
  108.  
  109. struct ResourceSpec {
  110.     OSType                             resType;                    /* 4-byte code  */
  111.     short                             resID;
  112. };
  113. typedef struct ResourceSpec ResourceSpec;
  114.  
  115. struct ComponentResource {
  116.     ComponentDescription             cd;                            /* Registration parameters */
  117.     ResourceSpec                     component;                    /* resource where Component code is found */
  118.     ResourceSpec                     componentName;                /* name string resource */
  119.     ResourceSpec                     componentInfo;                /* info string resource */
  120.     ResourceSpec                     componentIcon;                /* icon resource */
  121. };
  122. typedef struct ComponentResource ComponentResource;
  123.  
  124. typedef ComponentResource *ComponentResourcePtr;
  125. typedef ComponentResourcePtr *ComponentResourceHandle;
  126. struct ComponentPlatformInfo {
  127.     long                             componentFlags;                /* flags of Component */
  128.     ResourceSpec                     component;                    /* resource where Component code is found */
  129.     short                             platformType;                /* gestaltSysArchitecture result */
  130. };
  131. typedef struct ComponentPlatformInfo ComponentPlatformInfo;
  132.  
  133. struct ComponentResourceExtension {
  134.     long                             componentVersion;            /* version of Component */
  135.     long                             componentRegisterFlags;        /* flags for registration */
  136.     short                             componentIconFamily;        /* resource id of Icon Family */
  137. };
  138. typedef struct ComponentResourceExtension ComponentResourceExtension;
  139.  
  140. struct ComponentPlatformInfoArray {
  141.     long                             count;
  142.     ComponentPlatformInfo             platformArray[1];
  143. };
  144. typedef struct ComponentPlatformInfoArray ComponentPlatformInfoArray;
  145.  
  146. struct ExtComponentResource {
  147.     ComponentDescription             cd;                            /* registration parameters */
  148.     ResourceSpec                     component;                    /* resource where Component code is found */
  149.     ResourceSpec                     componentName;                /* name string resource */
  150.     ResourceSpec                     componentInfo;                /* info string resource */
  151.     ResourceSpec                     componentIcon;                /* icon resource */
  152.     long                             componentVersion;            /* version of Component */
  153.     long                             componentRegisterFlags;        /* flags for registration */
  154.     short                             componentIconFamily;        /* resource id of Icon Family */
  155.     long                             count;                        /* elements in platformArray */
  156.     ComponentPlatformInfo             platformArray[1];
  157. };
  158. typedef struct ExtComponentResource ExtComponentResource;
  159.  
  160. struct ComponentParameters {
  161.     UInt8                             flags;                        /* call modifiers: sync/async, deferred, immed, etc */
  162.     UInt8                             paramSize;                    /* size in bytes of actual parameters passed to this call */
  163.     short                             what;                        /* routine selector, negative for Component management calls */
  164.     long                             params[1];                    /* actual parameters for the indicated routine */
  165. };
  166. typedef struct ComponentParameters ComponentParameters;
  167.  
  168. struct ComponentRecord {
  169.     long                             data[1];
  170. };
  171. typedef struct ComponentRecord ComponentRecord;
  172.  
  173. typedef ComponentRecord *Component;
  174. struct ComponentInstanceRecord {
  175.     long                             data[1];
  176. };
  177. typedef struct ComponentInstanceRecord ComponentInstanceRecord;
  178.  
  179. typedef ComponentInstanceRecord *ComponentInstance;
  180. typedef long ComponentResult;
  181.  
  182. enum {
  183.     mpWorkFlagDoWork            = (1 << 0),
  184.     mpWorkFlagDoCompletion        = (1 << 1),
  185.     mpWorkFlagCopyWorkBlock        = (1 << 2),
  186.     mpWorkFlagDontBlock            = (1 << 3),
  187.     mpWorkFlagGetProcessorCount    = (1 << 4)
  188. };
  189.  
  190. struct ComponentMPWorkFunctionHeaderRecord {
  191.     UInt32                             headerSize;
  192.     UInt32                             recordSize;
  193.     UInt32                             workFlags;
  194.     UInt16                             processorCount;
  195.     UInt16                             unused;
  196. };
  197. typedef struct ComponentMPWorkFunctionHeaderRecord ComponentMPWorkFunctionHeaderRecord;
  198.  
  199. typedef ComponentMPWorkFunctionHeaderRecord *ComponentMPWorkFunctionHeaderRecordPtr;
  200. typedef pascal ComponentResult (*ComponentMPWorkFunctionProcPtr)(void *globalRefCon, ComponentMPWorkFunctionHeaderRecordPtr header);
  201.  
  202. #if GENERATINGCFM
  203. typedef UniversalProcPtr ComponentMPWorkFunctionUPP;
  204. #else
  205. typedef ComponentMPWorkFunctionProcPtr ComponentMPWorkFunctionUPP;
  206. #endif
  207.  
  208. enum {
  209.     uppComponentMPWorkFunctionProcInfo = kPascalStackBased
  210.          | RESULT_SIZE(SIZE_CODE(sizeof(ComponentResult)))
  211.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(void *)))
  212.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(ComponentMPWorkFunctionHeaderRecordPtr)))
  213. };
  214.  
  215. #if GENERATINGCFM
  216. #define NewComponentMPWorkFunctionProc(userRoutine)        \
  217.         (ComponentMPWorkFunctionUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppComponentMPWorkFunctionProcInfo, GetCurrentArchitecture())
  218. #else
  219. #define NewComponentMPWorkFunctionProc(userRoutine)        \
  220.         ((ComponentMPWorkFunctionUPP) (userRoutine))
  221. #endif
  222.  
  223. #if GENERATINGCFM
  224. #define CallComponentMPWorkFunctionProc(userRoutine, globalRefCon, header)        \
  225.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppComponentMPWorkFunctionProcInfo, (globalRefCon), (header))
  226. #else
  227. #define CallComponentMPWorkFunctionProc(userRoutine, globalRefCon, header)        \
  228.         (*(userRoutine))((globalRefCon), (header))
  229. #endif
  230. typedef pascal ComponentResult (*ComponentRoutineProcPtr)(ComponentParameters *cp, Handle componentStorage);
  231.  
  232. #if GENERATINGCFM
  233. typedef UniversalProcPtr ComponentRoutineUPP;
  234. #else
  235. typedef ComponentRoutineProcPtr ComponentRoutineUPP;
  236. #endif
  237.  
  238. enum {
  239.     uppComponentRoutineProcInfo = kPascalStackBased
  240.          | RESULT_SIZE(SIZE_CODE(sizeof(ComponentResult)))
  241.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(ComponentParameters *)))
  242.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(Handle)))
  243. };
  244.  
  245. #if GENERATINGCFM
  246. #define NewComponentRoutineProc(userRoutine)        \
  247.         (ComponentRoutineUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppComponentRoutineProcInfo, GetCurrentArchitecture())
  248. #else
  249. #define NewComponentRoutineProc(userRoutine)        \
  250.         ((ComponentRoutineUPP) (userRoutine))
  251. #endif
  252.  
  253. #if GENERATINGCFM
  254. #define CallComponentRoutineProc(userRoutine, cp, componentStorage)        \
  255.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppComponentRoutineProcInfo, (cp), (componentStorage))
  256. #else
  257. #define CallComponentRoutineProc(userRoutine, cp, componentStorage)        \
  258.         (*(userRoutine))((cp), (componentStorage))
  259. #endif
  260. typedef ComponentRoutineProcPtr ComponentRoutine;
  261. /*
  262.     The parameter list for each ComponentFunction is unique. It is 
  263.     therefore up to users to create the appropriate procInfo for their 
  264.     own ComponentFunctions where necessary.
  265. */
  266. typedef UniversalProcPtr ComponentFunctionUPP;
  267. #if GENERATINGCFM
  268. /* 
  269.     CallComponentUPP is a global variable exported from InterfaceLib.
  270.     It is the ProcPtr passed to CallUniversalProc to manually call a component function.
  271. */
  272. extern UniversalProcPtr CallComponentUPP;
  273. #endif
  274. #define ComponentCallNow( callNumber, paramSize ) \
  275.     FIVEWORDINLINE( 0x2F3C,paramSize,callNumber,0x7000,0xA82A )
  276.  
  277. /* Component Database Add, Delete, and Query Routines */
  278. extern pascal Component RegisterComponent(ComponentDescription *cd, ComponentRoutineUPP componentEntryPoint, short global, Handle componentName, Handle componentInfo, Handle componentIcon)
  279.  TWOWORDINLINE(0x7001, 0xA82A);
  280.  
  281. extern pascal Component RegisterComponentResource(ComponentResourceHandle tr, short global)
  282.  TWOWORDINLINE(0x7012, 0xA82A);
  283.  
  284. extern pascal OSErr UnregisterComponent(Component aComponent)
  285.  TWOWORDINLINE(0x7002, 0xA82A);
  286.  
  287. extern pascal Component FindNextComponent(Component aComponent, ComponentDescription *looking)
  288.  TWOWORDINLINE(0x7004, 0xA82A);
  289.  
  290. extern pascal long CountComponents(ComponentDescription *looking)
  291.  TWOWORDINLINE(0x7003, 0xA82A);
  292.  
  293. extern pascal OSErr GetComponentInfo(Component aComponent, ComponentDescription *cd, Handle componentName, Handle componentInfo, Handle componentIcon)
  294.  TWOWORDINLINE(0x7005, 0xA82A);
  295.  
  296. extern pascal long GetComponentListModSeed(void )
  297.  TWOWORDINLINE(0x7006, 0xA82A);
  298.  
  299. /* Component Instance Allocation and dispatch routines */
  300. extern pascal ComponentInstance OpenComponent(Component aComponent)
  301.  TWOWORDINLINE(0x7007, 0xA82A);
  302.  
  303. extern pascal OSErr CloseComponent(ComponentInstance aComponentInstance)
  304.  TWOWORDINLINE(0x7008, 0xA82A);
  305.  
  306. extern pascal OSErr GetComponentInstanceError(ComponentInstance aComponentInstance)
  307.  TWOWORDINLINE(0x700A, 0xA82A);
  308.  
  309. /* Direct calls to the Components */
  310. extern pascal long ComponentFunctionImplemented(ComponentInstance ci, short ftnNumber)
  311.  FIVEWORDINLINE(0x2F3C, 0x0002, 0xFFFD, 0x7000, 0xA82A);
  312.  
  313. extern pascal long GetComponentVersion(ComponentInstance ci)
  314.  FIVEWORDINLINE(0x2F3C, 0x0000, 0xFFFC, 0x7000, 0xA82A);
  315.  
  316. extern pascal long ComponentSetTarget(ComponentInstance ci, ComponentInstance target)
  317.  FIVEWORDINLINE(0x2F3C, 0x0004, 0xFFFA, 0x7000, 0xA82A);
  318.  
  319. /* Component Management routines */
  320. extern pascal void SetComponentInstanceError(ComponentInstance aComponentInstance, OSErr theError)
  321.  TWOWORDINLINE(0x700B, 0xA82A);
  322.  
  323. extern pascal long GetComponentRefcon(Component aComponent)
  324.  TWOWORDINLINE(0x7010, 0xA82A);
  325.  
  326. extern pascal void SetComponentRefcon(Component aComponent, long theRefcon)
  327.  TWOWORDINLINE(0x7011, 0xA82A);
  328.  
  329. extern pascal short OpenComponentResFile(Component aComponent)
  330.  TWOWORDINLINE(0x7015, 0xA82A);
  331.  
  332. extern pascal OSErr CloseComponentResFile(short refnum)
  333.  TWOWORDINLINE(0x7018, 0xA82A);
  334.  
  335. /* Component Instance Management routines */
  336. extern pascal Handle GetComponentInstanceStorage(ComponentInstance aComponentInstance)
  337.  TWOWORDINLINE(0x700C, 0xA82A);
  338.  
  339. extern pascal void SetComponentInstanceStorage(ComponentInstance aComponentInstance, Handle theStorage)
  340.  TWOWORDINLINE(0x700D, 0xA82A);
  341.  
  342. extern pascal long GetComponentInstanceA5(ComponentInstance aComponentInstance)
  343.  TWOWORDINLINE(0x700E, 0xA82A);
  344.  
  345. extern pascal void SetComponentInstanceA5(ComponentInstance aComponentInstance, long theA5)
  346.  TWOWORDINLINE(0x700F, 0xA82A);
  347.  
  348. extern pascal long CountComponentInstances(Component aComponent)
  349.  TWOWORDINLINE(0x7013, 0xA82A);
  350.  
  351. /* Useful helper routines for convenient method dispatching */
  352. extern pascal long CallComponentFunction(ComponentParameters *params, ComponentFunctionUPP func)
  353.  TWOWORDINLINE(0x70FF, 0xA82A);
  354.  
  355. extern pascal long CallComponentFunctionWithStorage(Handle storage, ComponentParameters *params, ComponentFunctionUPP func)
  356.  TWOWORDINLINE(0x70FF, 0xA82A);
  357.  
  358. extern pascal long DelegateComponentCall(ComponentParameters *originalParams, ComponentInstance ci)
  359.  TWOWORDINLINE(0x7024, 0xA82A);
  360.  
  361. extern pascal OSErr SetDefaultComponent(Component aComponent, short flags)
  362.  TWOWORDINLINE(0x701E, 0xA82A);
  363.  
  364. extern pascal ComponentInstance OpenDefaultComponent(OSType componentType, OSType componentSubType)
  365.  TWOWORDINLINE(0x7021, 0xA82A);
  366.  
  367. extern pascal Component CaptureComponent(Component capturedComponent, Component capturingComponent)
  368.  TWOWORDINLINE(0x701C, 0xA82A);
  369.  
  370. extern pascal OSErr UncaptureComponent(Component aComponent)
  371.  TWOWORDINLINE(0x701D, 0xA82A);
  372.  
  373. extern pascal long RegisterComponentResourceFile(short resRefNum, short global)
  374.  TWOWORDINLINE(0x7014, 0xA82A);
  375.  
  376. extern pascal OSErr GetComponentIconSuite(Component aComponent, Handle *iconSuite)
  377.  TWOWORDINLINE(0x7029, 0xA82A);
  378.  
  379. #endif
  380.  
  381. #if PRAGMA_ALIGN_SUPPORTED
  382. #pragma options align=reset
  383. #endif
  384.  
  385. #if PRAGMA_IMPORT_SUPPORTED
  386. #pragma import off
  387. #endif
  388.  
  389. #ifdef __cplusplus
  390. }
  391. #endif
  392.  
  393. #endif /* __COMPONENTS__ */
  394.  
  395.